Node / ReticulumProjects / MeshChatX.git / files / docs / en / installation.md

Displaying Rendered • View raw • Download

MeshChatX can be installed in several ways. All release artifacts that ship the web UI include pre-built frontend assets. You do not need Node.js on the machine that only runs the Python wheel or Docker image.

Browsers for the web UI: Safari 16.4+, Chrome 111+, Firefox 128+.

Release images are published to Docker Hub (T383838quad4io/meshchatx) and GHCR (T383838ghcr.io/quad4-software/meshchatx). Tag suffixes: none for the standard Alpine image, T383838-hardened for Chainguard/Wolfi, T383838-extra for Alpine plus i2pd and yggdrasil (T383838VARIANT=extra on the same Dockerfile).

Quick start with Compose:

T282828

Manual run with a named volume for persistence:

T282828

--restart unless-stopped Tffea00\

--init Tffea00\

--user T79c0ff1000:1000 Tffea00\

--security-opt no-new-privileges:true Tffea00\

--cap-drop ALL Tffea00\

--read-only Tffea00\

--tmpfs /tmp:noexec,nosuid,sizeTff7b72=256m Tffea00\

--tmpfs /home/meshchat:nosuid,sizeTff7b72=64m Tffea00\

--cpusTff7b72=T79c0ff2.0 Tffea00\

--memoryTff7b72=1g Tffea00\

--memory-reservationTff7b72=256m Tffea00\

--pids-limitTff7b72=T79c0ff512 Tffea00\

-p T79c0ff127.0.0.1:8000:8000 Tffea00\

-v meshchatx-config:/config Tffea00\

ghcr.io/quad4-software/meshchatx:latest

Default Compose maps T383838127.0.0.1:8000 on the host to port T3838388000 in the container. Data persists in the T383838meshchatx-config volume at T383838/config.

To bind a host directory instead, mount it at T383838/config. The container runs as UID 1000. The host directory must be writable by that user.

For a read-only mesh showcase on Coolify, deploy docker-compose.demo.yml. For a normal (non-demo) Coolify deployment, use docker-compose.coolify.yml.

• T383838MESHCHAT_DEMO_MODE=1 blocks outbound mesh actions and almost all API mutations.

• T383838MESHCHAT_AUTH=1 with default showcase password T383838demo (T383838MESHCHAT_DEMO_AUTH_PASSWORD).

• Optional T383838MESHCHAT_AUTH_PAGE_HINT shows custom text on the login page (for example T383838Username: demo and T383838Password: demo). Demo compose sets a default hint.

• T383838MESHCHAT_ALTCHA_ENABLED=1 and a strong T383838MESHCHAT_ALTCHA_HMAC_KEY (required in demo compose via T383838:?). The UI uses ALTCHA widget v3 with T383838PBKDF2/SHA-256 challenges from T383838/api/v1/auth/altcha/challenge.

• Assign a domain with container port 8000, for example T383838https://meshchatx.example.com:8000.

• Do not set T383838MESHCHAT_AUTH_BYPASS=1 on a public host.

1. Download T383838reticulum_meshchatx-*-py3-none-any.whl from releases.

2. Install with pip, pipx, or uv:

T282828

3. Start the server:

T282828

meshchatx --headless --host T79c0ff127.0.0.1

The T383838meshchat command is a compatibility alias for the same entry point.

On hosts where T383838libopus is installed but T383838libogg is not, LXST's vendored pyogg can raise T383838NameError: c_int_p on import. MeshChatX applies a ctypes compatibility fix at startup (the same patch Docker runs after install). Optional telephony audio still needs the usual Opus/Ogg system libraries when you use those codecs.

T282828

T282828

Adjust the filename for your architecture.

T282828

uv run python -m meshchatx.meshchat --headless --host T79c0ff127.0.0.1

Useful task targets include T383838task format, T383838task lint, T383838task test, and T383838task build.

On first run MeshChatX creates a random Reticulum identity if you do not pass one on the command line. The identity file is stored under your configured storage directory.

Open the UI at the host and port you chose. HTTPS is enabled by default with a self-signed certificate unless you pass T383838--no-https or provide your own PEM files.

Common flags and environment variables:

CLI flags override environment variables when both are set.

The Reticulum HTML manual is fetched from the upstream website master branch at build time by default (clearnet ZIP). There is no in-app clearnet refresh. After cloning the repository, or before packaging a release, run:

T282828

CI release builds use the clearnet path. Without a bundled copy the Reticulum tab may show an upload prompt until you build docs or upload a manual ZIP offline.

MeshChatX includes optional tooling to pull T383838rns, T383838lxmf, T383838lxst, and the Reticulum manual from markqvist's rngit remotes over the mesh instead of clearnet.

Note: Installing Python packages over RNS is significantly slower than PyPI and is intended for use in environments with mesh access but restricted clearnet. PyPI remains the default and recommended path for CI and standard development.

This uses pip-rns for the Python packages and T383838git + T383838git-remote-rns for the docs tree. Default aliases live in T383838scripts/pip-rns/aliases.

Bootstrap note: pip-rns needs a working Reticulum stack to reach the remotes. Install T383838rns once from PyPI, a wheel, or an existing environment, then use the mesh path for updates.

T282828

task deps:backend:rns

T8b949e# Optional: Bundle the Reticulum manual from the rngit website remote

task docs:rns

Equivalent direct commands:

T282828

Set T383838PIP_RNS_CONFIG to point at another aliases directory if needed. T383838MESHCHATX_RETICULUM_DOCS_URL=rns://... also works for a custom website remote.

You can supply an identity at startup:

• T383838--identity-file /path/to/identity

• T383838--identity-base64 or T383838--identity-base32 with the corresponding environment variables

Otherwise MeshChatX generates one and saves it under T383838<storage>/identity. Additional identities are created from the Identities page. Each identity has its own database, LXMF router, and settings while sharing one Reticulum process.

1. Add at least one interface so Reticulum can reach peers.

2. Review Settings for display name, theme, language, and LXMF stamp costs.

3. Enable telephone in settings if you plan to use audio calls.

4. Open Documentation for MeshChatX guides and the Reticulum manual offline.

Platform-specific notes live under Platform guides in this documentation bundle.